<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">

<html><head><title>Component Writer&rsquo;s Guide - NewAC</title><link rel="stylesheet" type="text/css" href="../../../styles/main.css"><script language=JavaScript src="../../../javascript/main.js"></script><script language=JavaScript src="../../../javascript/searchdata.js"></script></head><body class="ContentPage" onLoad="NDOnLoad()"><script language=JavaScript><!--
if (browserType) {document.write("<div class=" + browserType + ">");if (browserVer) {document.write("<div class=" + browserVer + ">"); }}// --></script>

<!--  Generated by Natural Docs, version 1.4 -->
<!--  http://www.naturaldocs.org  -->

<!-- saved from url=(0026)http://www.naturaldocs.org -->




<div id=Content><div class="CSection"><div class=CTopic id=MainTopic><h1 class=CTitle><a name="Component_Writer's_Guide"></a>Component Writer&rsquo;s Guide</h1><div class=CBody><p>This tutorial will teach you how to write input and output components for the NewAC components suite.&nbsp; In this tutorial we will write two simple components, TDemoWaveIn and TDemoWaveOut, designed for reading and writing audio data stored in Wave files in raw PCM format.&nbsp; These components are defined in the <a href="../../demos/Tutorial/ComponentsDemo/ComponentsDemo-pas.html#Components_Demo" class=LSection id=link1 onMouseOver="ShowTip(event, 'tt1', 'link1')" onMouseOut="HideTip('tt1')">Components Demo</a> (which you can find in the <b>demos\Tutorial\ComponentsDemo</b> folder).&nbsp; There are TWaveIn and TWaveOut components in the NewAC package that are more sophisticated and more suitable for handling Wave files in real live.&nbsp; The two components discussed here are just demos.&nbsp; TDemoWaveIn and TDemoWaveOut are writing so as to make it clear how NewAC works.&nbsp; But they are not the only examples.&nbsp; Any NewAC component may be used as a demo and the base for creating new components.</p><!--START_ND_SUMMARY--><div class=Summary><div class=STitle>Summary</div><div class=SBorder><table border=0 cellspacing=0 cellpadding=0 class=STable><tr class="SMain"><td class=SEntry><a href="#Component_Writer's_Guide" >Component Writer&rsquo;s Guide</a></td><td class=SDescription>This tutorial will teach you how to write input and output components for the NewAC components suite. </td></tr><tr class="SGeneric SIndent1 SMarked"><td class=SEntry><a href="#Supporting_a_New_Audio_Format" >Supporting a New Audio Format</a></td><td class=SDescription>Writing new components for NewAC is quite easy. </td></tr><tr class="SGeneric SIndent1"><td class=SEntry><a href="#Data_Handling" >Data Handling</a></td><td class=SDescription>NewAC handles data as the flow of digital audio frames. </td></tr><tr class="SSection"><td class=SEntry><a href="#Writing_an_Input_Component" >Writing an Input Component</a></td><td class=SDescription>Your main goal as an input component writer is to decode audio data from the format you are working with into the NewAC format and to provide additional parameters for representing an audio stream. </td></tr><tr class="SSection"><td class=SEntry><a href="#Writing_an_Output_Component" >Writing an Output Component</a></td><td class=SDescription>When writing an output component you always have to override three methods: Prepare, DoOutput and Done. </td></tr></table></div></div><!--END_ND_SUMMARY--></div></div></div>

<div class="CGeneric"><div class=CTopic><h3 class=CTitle><a name="Supporting_a_New_Audio_Format"></a>Supporting a New Audio Format</h3><div class=CBody><p>Writing new components for NewAC is quite easy.&nbsp; Due to the object oriented nature of NewAC you don&rsquo;t have to write everything from scratch.&nbsp; When you write an input component you take one of the NewAC classes (usually TAuFileIn) as your base class and override some of its methods in your new class.&nbsp; When you write an output component you usually make a new class descending from TAuFileOut and override some of the base class&rsquo; methods in your new class.&nbsp; In case of the input component descending from TAuFileIn you have to override four or three base class&rsquo; methods (depending on what functionality you want to provide), and in case of the output component that descends from TAuFileOut you always have to override just three base methods.</p></div></div></div>

<div class="CGeneric"><div class=CTopic><h3 class=CTitle><a name="Data_Handling"></a>Data Handling</h3><div class=CBody><p>NewAC handles data as the flow of digital audio frames.&nbsp; Each sample consists of one or more integer samples (the number of samples in the frame is equal to the number of channels, 1 for mono, 2 for stereo and so on).&nbsp; The 8-bit samples are unsigned Bytes, and the 16-bit samples are signed SmallInts.&nbsp; The samples for all channels are interleaved.&nbsp; Thus one sample for mono 8-bit sound is 1 byte long, while one sample for stereo 16-bit sound is 4 bytes long.&nbsp; As far as I know there is some ambiguity in English terminology regarding frames and samples.&nbsp; What we call &ldquo;frames&rdquo; here is often called &ldquo;samples&rdquo;, and NewAC sometimes speaks of samples instead of frames.</p></div></div></div>

<div class="CSection"><div class=CTopic><h2 class=CTitle><a name="Writing_an_Input_Component"></a>Writing an Input Component</h2><div class=CBody><p>Your main goal as an input component writer is to decode audio data from the format you are working with into the NewAC format and to provide additional parameters for representing an audio stream.&nbsp; These additional parameters are the number of bits per sample (8 or 16), the number of channels, and the sample rate in Hz.&nbsp; The additional parameter that you may, but not required to, provide is the audio stream size in bytes.&nbsp; Note that when you provide the audio stream size it is the size of the decoded audio stream, not the size of the formatted stream you are decoding from.</p><p><b>Overriding Methods</b></p><p>What are these three methods that you have to override in your new input component?&nbsp; Take a file metaphor.&nbsp; When working with files you need at least the three functions: for opening the file, for reading the file (it is usually done in a loop) and for closing the file when you are done.&nbsp; The three methods of TAuFileIn that you have to override do just that -- opening, reading and closing the file (or, more generally, -- a stream).&nbsp; The forth method, which is not mandatory, performs seeking in the input stream.&nbsp; For opening and closing the file you ovrride the OpenFile and the CloseFile methods respectively.&nbsp; For reading data you override the GetDataInternal method, and for seeking you override the SeekInternal method.</p></div></div></div>

<div class="CSection"><div class=CTopic><h2 class=CTitle><a name="Writing_an_Output_Component"></a>Writing an Output Component</h2><div class=CBody><p>When writing an output component you always have to override three methods: Prepare, DoOutput and Done.&nbsp; The file metaphor may again be useful.&nbsp; Prepare corresponds to opening the file (for writing), DoOutput performs actual data output (it is called in a loop by NewAC) and Done performs operations analogous to closing the file.&nbsp; Among other things an output component inherits from TAuFileOut the FInput property.&nbsp; This property points to an input component (assigned to the output component&rsquo;s  Input published property).&nbsp; Note that FInput has type of TAuInput, and not TAuFileIn.&nbsp; The TAuInput class is the base class for all  NewAC input classes, not only those that deal with streams.&nbsp; Your output component initializes its input by calling the FInput.Init method and reads incoming audio parameters from FInput&rsquo;s properties and sets up encoder accordingly.&nbsp; The DoOutput method usually calls either Input&rsquo;s GetData method (which is described above) or the CopyData method that is based on GetData but provides a different interface.&nbsp; When the output component finishes its job it calls the FInput.Flush method to close the input.</p></div></div></div>

</div><!--Content-->


<div id=Footer>Content &copy; 2008 Andrei Borovsky. Design &copy; 2008 Wayne Thursby. <b><u><a href="http://symmetrica.net/newac">Go to the project's main page</a></u></b>&nbsp; &middot;&nbsp; <a href="http://www.naturaldocs.org">Generated by Natural Docs</a></div><!--Footer-->


<div id=Menu><div class=MTitle>NewAC<div class=MSubTitle>v1.7.1</div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent1')">Documentation</a><div class=MGroupContent id=MGroupContent1><div class=MEntry><div class=MFile><a href="introduction-txt.html">Quick Introduction to NewAC</a></div></div><div class=MEntry><div class=MFile><a href="about_documentation-txt.html">About the Documentation</a></div></div><div class=MEntry><div class=MFile id=MSelected>Component Writer&rsquo;s Guide</div></div><div class=MEntry><div class=MFile><a href="license-txt.html">License</a></div></div><div class=MEntry><div class=MFile><a href="tips_and_tricks-txt.html">Tips &amp; Tricks</a></div></div><div class=MEntry><div class=MFile><a href="newac-txt.html">About New Audio Components</a></div></div><div class=MEntry><div class=MFile><a href="features-txt.html">NewAC Main Features List</a></div></div></div></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent2')">Main Units</a><div class=MGroupContent id=MGroupContent2><div class=MEntry><div class=MFile><a href="../../src/ACS_AudioMix-pas.html">ACS_AudioMix</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_CDROM-pas.html">ACS_CDROM</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Classes-pas.html">ACS_Classes</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Converters-pas.html">ACS_Converters</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_DXAudio-pas.html">ACS_DXAudio</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_FLAC-pas.html">ACS_FLAC</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Filters-pas.html">ACS_Filters</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_LAME-pas.html">ACS_LAME</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_MAC-pas.html">ACS_MAC</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_MPC-pas.html">ACS_MPC</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_OptimFROG-pas.html">ACS_OptimFROG</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_smpeg-pas.html">ACS_SMPEG</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Streams-pas.html">ACS_Streams</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_TTA-pas.html">ACS_TTA</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Tags-pas.html">ACS_Tags</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Vorbis-pas.html">ACS_Vorbis</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_WavPack-pas.html">ACS_WavPack</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Wave-pas.html">ACS_Wave</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_WinMedia-pas.html">ACS_WinMedia</a></div></div><div class=MEntry><div class=MFile><a href="../../src/AudioDMO-pas.html">AudioDMO</a></div></div><div class=MEntry><div class=MFile><a href="../../src/AudioPass-pas.html">AudioPass</a></div></div><div class=MEntry><div class=MFile><a href="../../src/AuSampleRate-pas.html">AuSampleRate</a></div></div><div class=MEntry><div class=MFile><a href="../../src/NewAC_AVI-pas.html">NewAC_AVI</a></div></div><div class=MEntry><div class=MFile><a href="../../src/libsamplerate-pas.html">libsamplerate.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/MACDll-pas.html">MACDll.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ogg-pas.html">ogg.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ovencode-pas.html">ovencode</a></div></div><div class=MEntry><div class=MFile><a href="../../src/VorbisEnc-pas.html">VorbisEnc.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/VorbisFile-pas.html">VorbisFile.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/WaveConverter-pas.html">WaveConverter.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/WavPackDLL-pas.html">WavPackDLL</a></div></div><div class=MEntry><div class=MFile><a href="../../src/wmfintf-pas.html">wmfintf.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/NewAC_DSP-pas.html">NewAC_DSP</a></div></div></div></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent3')">Converted C/C++ Headers</a><div class=MGroupContent id=MGroupContent3><div class=MEntry><div class=MFile><a href="../../src/CDRip-pas.html">CDRip</a></div></div><div class=MEntry><div class=MFile><a href="../../src/Codec-pas.html">Codec</a></div></div><div class=MEntry><div class=MFile><a href="../../src/DSWrapper-pas.html">DSWrapper</a></div></div><div class=MEntry><div class=MFile><a href="../../src/FLAC-pas.html">FLAC</a></div></div><div class=MEntry><div class=MFile><a href="../../src/libwma1-pas.html">libwma1.pas</a></div></div><div class=MEntry><div class=MFile><a href="../../src/_DirectSound-pas.html">_DirectSound</a></div></div><div class=MEntry><div class=MFile><a href="../../src/_DXTypes-pas.html">_DXTypes</a></div></div></div></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent4')">Utility Units</a><div class=MGroupContent id=MGroupContent4><div class=MEntry><div class=MFile><a href="../../src/ACS_Misc-pas.html">ACS_Misc</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Procs-pas.html">ACS_Procs</a></div></div><div class=MEntry><div class=MFile><a href="../../src/acs_reg-pas.html">ACS_Reg</a></div></div><div class=MEntry><div class=MFile><a href="../../src/ACS_Types-pas.html">ACS_Types</a></div></div></div></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent5')">Tutorials</a><div class=MGroupContent id=MGroupContent5><div class=MEntry><div class=MFile><a href="../../demos/Tutorial/AudioProcessor/Main-pas.html">Audio Processor</a></div></div><div class=MEntry><div class=MFile><a href="../../demos/Tutorial/ComponentsDemo/ComponentsDemo-pas.html">Components Demo</a></div></div><div class=MEntry><div class=MFile><a href="../../demos/Recorders-rippers/Rip'n'listen/Main-pas.html">Rip&rsquo;n&rsquo;Listen Demo</a></div></div></div></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent6')">DUnit</a><div class=MGroupContent id=MGroupContent6><div class=MEntry><div class=MFile><a href="../../dunit/Test_ACS_FLAC-pas.html">ACS_FLAC TestCases</a></div></div><div class=MEntry><div class=MFile><a href="../../dunit/Test_ACS_MAC-pas.html">ACS_MAC TestCases</a></div></div><div class=MEntry><div class=MFile><a href="../../dunit/Test_ACS_WavPack-pas.html">ACS_WavPack TestCases</a></div></div><div class=MEntry><div class=MFile><a href="../../dunit/uLog-pas.html">uLog</a></div></div><div class=MEntry><div class=MFile><a href="../../dunit/uTestBase-pas.html">uTestBase</a></div></div><div class=MEntry><div class=MFile><a href="../../dunit/uUtility-pas.html">uUtility</a></div></div></div></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent7')">Index</a><div class=MGroupContent id=MGroupContent7><div class=MEntry><div class=MIndex><a href="../../../index/General.html">Everything</a></div></div><div class=MEntry><div class=MIndex><a href="../../../index/Classes.html">Classes</a></div></div><div class=MEntry><div class=MIndex><a href="../../../index/Constants.html">Constants</a></div></div><div class=MEntry><div class=MIndex><a href="../../../index/Files.html">Files</a></div></div><div class=MEntry><div class=MIndex><a href="../../../index/Functions.html">Functions</a></div></div><div class=MEntry><div class=MIndex><a href="../../../index/Properties.html">Properties</a></div></div><div class=MEntry><div class=MIndex><a href="../../../index/Types.html">Types</a></div></div><div class=MEntry><div class=MIndex><a href="../../../index/Variables.html">Variables</a></div></div></div></div></div><script type="text/javascript"><!--
var searchPanel = new SearchPanel("searchPanel", "HTML", "../../../search");
--></script><div id=MSearchPanel class=MSearchPanelInactive><input type=text id=MSearchField value=Search onFocus="searchPanel.OnSearchFieldFocus(true)" onBlur="searchPanel.OnSearchFieldFocus(false)" onKeyUp="searchPanel.OnSearchFieldChange()"><select id=MSearchType onFocus="searchPanel.OnSearchTypeFocus(true)" onBlur="searchPanel.OnSearchTypeFocus(false)" onChange="searchPanel.OnSearchTypeChange()"><option  id=MSearchEverything selected value="General">Everything</option><option value="Classes">Classes</option><option value="Constants">Constants</option><option value="Files">Files</option><option value="Functions">Functions</option><option value="Properties">Properties</option><option value="Types">Types</option><option value="Variables">Variables</option></select></div><script language=JavaScript><!--
HideAllBut([1], 8);// --></script></div><!--Menu-->



<!--START_ND_TOOLTIPS-->
<div class=CToolTip id="tt1"><div class=CSection>This unit is a demo showing how to build new input and output components for NewAC.</div></div><!--END_ND_TOOLTIPS-->




<div id=MSearchResultsWindow><iframe src="" frameborder=0 name=MSearchResults id=MSearchResults></iframe><a href="javascript:searchPanel.CloseResultsWindow()" id=MSearchResultsWindowClose>Close</a></div>


<script language=JavaScript><!--
if (browserType) {if (browserVer) {document.write("</div>"); }document.write("</div>");}// --></script></body></html>